home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 1.iso / DEMON / UTILS / LZH_FRONT.ZIP / !Lzh / LZHModules / ReadMe < prev   
Text File  |  1997-04-28  |  8KB  |  190 lines
  1. Help file for the LZH module (version 0.02).
  2. ———————————————————————————————————————————————————
  3.  
  4. LZH as freeware:
  5. ————————————————
  6.  
  7. This directory and it's contents are FREEWARE, and all it's files may be
  8. copied freely in part or whole provided that they are not altered and no
  9. charge is made for them. This means you can use any of the modules provided in
  10. any application you choose including commerical software provided they are not
  11. alterd and I am credited for them.
  12.  
  13. The modules contained within this directory are version 0.02 of my LZH
  14. module. They are similar to John Kortink's LZW modules but they provide
  15. significantly greater compression with similar overheads (only 12k on
  16. decompression). The compression techniques used are a variable size Finite
  17. window technique with secondary dynamic huffman compression similar to
  18. gzip/zip/pkzip (but not the same). The modules are written in 100% lovingly
  19. handcrafted ARM code and are very fast (relatively) on compress and
  20. decompress.
  21.  
  22. There are currently two modules, LZH and LZHD. The LZH module allows both
  23. compression/decompression of files, and the LZHD module allows just
  24. decompression of files.
  25.  
  26. Note on Wacky-Talky versions:
  27. —————————————————————————————
  28.  
  29. Along with the system module versions there are also versions of the modules
  30. supplied in Wacky-Talky format. Wacky-Talky is a link manager which provides a
  31. nice new module format and a huge load of lovely extras. Copies of Wacky-Talky
  32. can be obtained from hensa. The Wacky-Talky DLR chunk number for LZH is &400
  33. and for LZHD is &401, and these modules provide support for automatic
  34. decompression of WT modules.
  35.  
  36. Compression/Decompression Speeds:
  37. —————————————————————————————————
  38.  
  39. These test were run on my Risc PC 600 with the screen switched off (i.e. no
  40. screen overheads). :
  41.  
  42. Data          Source code (114k)  Complex Screen (384k)  Large text file (782k)
  43.               (&1C92F bytes)      (&600B8 bytes)         (&C3649 bytes)
  44.               Write Read Size     Write Read Size        Write Read Size
  45.  
  46. Package
  47.  
  48. gzip -9       440   93   &9901    1745  117  &4E98       3507  339  &3CA34
  49. LZH 0.01      527   76   &977E    5074  66   &4D14       -     -    -
  50. LZH 0.02      469   74   &977E    3567  64   &4D14       4672  310  &3BA17
  51.  
  52. Unfortunatly it is difficult to provide an accurate means of speed comparison.
  53. Needless to say due to the different "tuning" of algorithms there are cases
  54. where the one will be "better" than the other. In fact LZH often compresses
  55. faster (where gzip's "speed for the cost of compression" techniques don't
  56. help), and gzip sometimes decompresses faster. Generaly though the LZH modules
  57. compress better than gzip because of the use of a 64k window (this is also the
  58. reason why LZH isn't SIGNIFICANTLY faster on compressthan gzip).
  59.  
  60. If you have any comments/bugs/ideas, then mail me at oramd@cs.man.ac.uk and I
  61. will be only too happy to sort them out.
  62.  
  63. Dan.
  64.  
  65. LZH SWIs:
  66. —————————
  67.  
  68. NOTE:    In the case of the Wacky-Talky modules, all registers except R0 are
  69. moved up one (i.e. R1 becomes R2, R2 becomes R3 etc.).
  70.  
  71.     LZH_Compress (SWI &5F401):
  72.     ——————————————————————————
  73.  
  74.     On Entry:
  75.  
  76.         R0 = flags:
  77.                 bit 0: 0=> no effect.
  78.                        1=> R1 is file handle.
  79.                 bit 1: 0=> no effect.
  80.                        1=> R1 is pointer to memory location for compressed data.
  81.                 bit 2: 0=> no effect.
  82.                        1=> use less memory for compress at the cost of speed
  83.                            (not particularly useful in this version).
  84.         R1 = If bits 0 & 1 of R0 are unset then pointer to filename.
  85.         R2 = Pointer to start of memory to compress.
  86.         R3 = Length of data (in bytes) to be compressed.
  87.  
  88.     On Exit:
  89.  
  90.         If bit1 of R0 is set on entry
  91.         R0 = Compressed size.
  92.         All other registers preserved
  93.  
  94.         Otherwise
  95.         All registers preserved.
  96.  
  97.  
  98.     This call saves the block of memory indicated by R2 and R3 to the
  99. filename/file handle/memory pointed to by R1. The save block will be checked
  100. for validity and an error returned if it contains addresses outside valid
  101. memory. The compression routines require varying amounts of memory. This will
  102. be about 640k for all files >64k in length and significantly less for shorter
  103. files - this is a bit on the heavy side, but is necessary to keep speed within
  104. sensible boundaries. Compression, although relatively very fast for this type
  105. can be INCREDIBLY slow (minutes for a few hundred k in certain special cases),
  106. so don't think the computer has crashed if the disc light hasn't flickered for
  107. ages. I have made no attempt to deal with this since the module is intended as
  108. a programmers tool for mainly read use and reading does not suffer from the
  109. same trouble.
  110.  
  111.     NOTE: Obviously there is no support for this SWI in the read only
  112. module.
  113.  
  114. LZH_DeCompress & LZHD_DeCompress (SWI &5F400 & SWI 5F440 in LZHD):
  115. ——————————————————————————————————————————————————————————————————
  116.  
  117.     On Entry:
  118.  
  119.         R0 = flags:
  120.                 bit 0: 0=> no effect.
  121.                        1=> R1 is file handle.
  122.                            This will use the current file pointer as start of
  123.                            of compressed data and will return with the file
  124.                            pointer pointing to the byte after the end of the
  125.                            LZH data.
  126.                 bit 1: 0=> no effect.
  127.                        1=> R1 is pointer to memory location for compressed data.
  128.                            This memory is validated.
  129.                 bit 2: 0=> no effect.
  130.                        1=> If set then no decompression is performed and the
  131.                            uncompressed size is returned only.
  132.  
  133.         R1 = If bits 0 & 1 of R0 are unset then pointer to filename.
  134.         R2 = Address in memory to decompress file to, this will be validated
  135.              to the uncompressed length.
  136.  
  137.     On Exit:
  138.  
  139.  
  140.     Exit:  R0 = uncompressed size.
  141.            R2 = Pointer to byte after source block (if memory->memory).
  142.            All other registers preserved.
  143.  
  144.     This call allows decompression of data from a file/memory to the memory
  145. address pointed to by R2. Any memory will be validated and an error returned if
  146. it is invalid, although the file will NOT be checked whilst decompressing to
  147. see if it is a valid LZH file (this would greatly impair performance). The
  148. file pointed to by R1 can be of any type. It is worth noting decompression
  149. only requires 12k and is very fast.
  150.  
  151. Further notes on compression:
  152. —————————————————————————————
  153.  
  154.     These modules are designed for the compression of code/data within
  155. applications. It may also be the case that you wish to make auto
  156. decompressing code/modules etc. and for this I would recommend !Crunch by
  157. BASS (you can get it from their web page or possibly from p.d. libraries).
  158. This provides less compression than these LZH modules (not always much less,
  159. but sometimes a lot less), and the decompression requires no overheads. If
  160. you're trying to compress something I recommend checking this out. For
  161. interests sake I think it uses just a finite window compression technique
  162. (but it seems a bit fast for this, unless it is using a small window).
  163.  
  164. History:
  165. ————————
  166.  
  167.     0.01  :  (revisions to 0.01 beta test)
  168.     
  169.           -  Added in extra options to allow memory to memory, file handle
  170.              to memory etc. transfers.
  171.           -  Realised that I'd made a very stupid mistake with the dynamic
  172.              huffman routines, and they were claiming twice as much memory as
  173.              needed.
  174.           -  Made the LZHD module claim memory only when it needed it.
  175.           -  Finally included the facility to check on the uncompressed size of
  176.              a file.
  177.  
  178.     0.02  :
  179.  
  180.           -  Made Wacky-Talky versions of the LZH modules.
  181.           -  Minor change to LZH_DeCompress, if file handle is supplied it now
  182.              takes the current file pointer as start of input stream.
  183.           -  LZH_DeCompress now returns updated file pointer or address of next
  184.              byte in the input stream (in R2).
  185.           -  Slight speed improvement (re-coded a couple of loops and changed
  186.              hash key algorithm).
  187.           -  Removed the less memory option because it was useless.
  188.           -  Stopped the 64k finite window being used as default. The size of
  189.              the window is now equivalent to the size of the file (thus less
  190.              memory is used) up to a maximum of 64k.